% !TEX TS-program = pdflatex
% !TEX encoding = UTF-8 Unicode

% This is a simple template for a LaTeX document using the "article" class.
% See "book", "report", "letter" for other types of document.

\documentclass[11pt]{article} % use larger type; default would be 10pt

\usepackage[utf8]{inputenc} % set input encoding (not needed with XeLaTeX)

%%% Examples of Article customizations
% These packages are optional, depending whether you want the features they provide.
% See the LaTeX Companion or other references for full information.

%%% PAGE DIMENSIONS
\usepackage{geometry} % to change the page dimensions
\geometry{a4paper} % or letterpaper (US) or a5paper or....
% \geometry{margins=2in} % for example, change the margins to 2 inches all round
% \geometry{landscape} % set up the page for landscape
%   read geometry.pdf for detailed page layout information

\usepackage{graphicx} % support the \includegraphics command and options

% \usepackage[parfill]{parskip} % Activate to begin paragraphs with an empty line rather than an indent

%%% PACKAGES
\usepackage{booktabs} % for much better looking tables
\usepackage{array} % for better arrays (eg matrices) in maths
%\usepackage{paralist} % very flexible & customisable lists (eg. enumerate/itemize, etc.)
\usepackage{verbatim} % adds environment for commenting out blocks of text & for better verbatim
\usepackage{subfig} % make it possible to include more than one captioned figure/table in a single float
% These packages are all incorporated in the memoir class to one degree or another...

%%% HEADERS & FOOTERS
\usepackage{fancyhdr} % This should be set AFTER setting up the page geometry
\pagestyle{fancy} % options: empty , plain , fancy
\renewcommand{\headrulewidth}{0pt} % customise the layout...
\lhead{}\chead{}\rhead{}
\lfoot{}\cfoot{\thepage}\rfoot{}

%%% SECTION TITLE APPEARANCE
%\usepackage{sectsty}
%\allsectionsfont{\sffamily\mdseries\upshape} % (See the fntguide.pdf for font help)
% (This matches ConTeXt defaults)

%%% ToC (table of contents) APPEARANCE
%\usepackage[nottoc,notlof,notlot]{tocbibind} % Put the bibliography in the ToC
%\usepackage[titles,subfigure]{tocloft} % Alter the style of the Table of Contents
%\renewcommand{\cftsecfont}{\rmfamily\mdseries\upshape}
%\renewcommand{\cftsecpagefont}{\rmfamily\mdseries\upshape} % No bold!

%%% END Article customizations

%%% The "real" document content comes below...

\title{AmiCoPyJava Documentation. User Guide. \footnote{reflects \texttt{AmiCo} 0.0.1}}
\author{Sergey Karakovskiy \footnote{sergey@idsia.ch}, Nikolay Sohryakov \footnote{Nikolay.Sohryakov@gmail.com}}
%\date{} % Activate to display a given date or no date (if empty),
         % otherwise the current date is printed 

\begin{document}
\maketitle

\section{AmiCoPyJava}
\texttt{AmiCoPyJava} is a library, that makes possible to call \texttt{Java} methods from your \texttt{Python} script without a line of code you have to write in \texttt{C/C++}. The \texttt{Python} source-code is so-called "active code", and the \texttt{Java} code is passive one. This part of the document describes how does \texttt{AmiCoPyJava} work and how to use it.

This native bridge is possible due to native \texttt{C++} bindings for both \texttt{Java} and \texttt{Python}. Library allows to invoke both static and non-static methods of a target \texttt{Java} class and provides complete access to \texttt{JNI}\footnote{\texttt{Java} Native Interface} methods from \texttt{Python}. In future support for multiple class loading will be added.

\subsection{AmiCoPyJava Methods}
There are two kinds of methods: 
\begin{enumerate}
	\item methods returns a value of primitive type
	\item methods returns an array of primitive types
\end{enumerate}
Values of basic types are passed between \texttt{Java} and \texttt{AmiCo}, \texttt{AmiCo} and \texttt{Python}: \emph{numeric} and \emph{floating point} types, \emph{strings} and \emph{arrays} of primitive types. Full  specification of supported types is presented in Table~\ref{table:PythonJavaTypes}.
\begin{table}[hp]
\center{
\begin{tabular}{ | c | c | c |  c | }
	\hline
	Python			& ctypes		& C++                 		& Java \\ \hline \hline
	1-character string 	& c\_ushort	& unsigned short 		&char \\ \hline
	int/long			& c\_ubyte		& unsigned char  		& boolean \\ \hline
	int/long			& c\_byte		& signed char	     		& byte \\ \hline
	int/long			& c\_short		& short	 	  		& short \\ \hline
	int/long			& c\_int		& int		     			& int \\ \hline
	int/long			& c\_longlong	& long long     			& long \\ \hline
	float				& c\_float		& float		     		& float \\ \hline
	float				& c\_double	& double	     			& double \\ \hline
	String or None		& c\_char\_p	& char* (NUL terminated)	& String \\ \hline
	Tuple				& py\_object	& $<$type$>$**		& native array of $<$type$>$ \\
 	\hline
\end{tabular}
}\caption{Correspondance for types in \texttt{Python},\texttt{ C++}, \texttt{Java}  } \label{table:PythonJavaTypes}
\end{table}

\subsection{Initialization}
\texttt{void amicoInitialize(int nOptions = 0, ...)} creates \texttt{JVM} with given startup options(like parameters of the function). It takes number of arguments as first parameter which is followed by string arguments matching this number. These are the JVM startup options. For example:
\begin{verbatim}
libamico.amicoInitialize(1, "-Xmn256M")
\end{verbatim}
\texttt{void loadJavaClass(const char* javaClassName)} loads and instantiates the \texttt{Java} class. This class contains methods to be called. For example:
\begin{verbatim}
libamico.loadJavaClass("helloUniverce")
\end{verbatim}
It takes one parameter -- name of the class to be loaded.

If they are any errors during initialization process, detailed error messages are emitted to standard error output. That's it! Setup is finished and methods from your Java class are available for invokation.

Finally, destroy the \texttt{JVM} with \texttt{destroyEnvironment()} function.

\subsection {Accessing \texttt{Java} class methods}
To access any non-static method of the Java class you first have to store method's ID using \texttt{void* getMethod(const char* mName, const char* mSign)} function. It takes a name of the method and it's signature as parameters and returns ID of the method if found or \texttt{NULL} otherwise. After that you can call that method using one of the functions from the \texttt{call<Type>Method} group where \texttt{<Type>} is a type of returning value (e.g. \texttt{callIntMethod})

There are functions of three kings: functions returning a value of any primitive type and functions returning an array of primitive type values, void functions. To call needed method you should  choice a method accordingly  to the type of the returning value of the \texttt{Java} method. For instance, a method \texttt{int sum(int a, int b, int c)} in your \texttt{Java} class is a method of interest:
\begin{verbatim}
#will give you an ID of the method
sumOfThree = libamico.getMethod("sumOfThree", "(III)I")   
#will call a \texttt{sum} method and return you a result as int
res = libamico.callIntMethod(sumOfThree, 1, 2, 3) 
\end{verbatim}
Sometimes \texttt{Python} doesn't know how to interpret a certain type so you should manually declare type(s) of the function options using an \texttt{argtype} property of the function in \texttt{Python} script. First parameter in every function will always be a \texttt{ctypes.c\_void\_p} and another could have any type from \texttt{ctypes}:
\begin{verbatim}
sumOfThree = libamico.getMethod("sumOfThree", "(III)I")
# args types
libamico.callIntMethod.argtypes = [ctypes.c_void_p, c_int, c_int, c_int]
# result type
libamico.callIntMethod.restype = c_int
res = libamico.callIntMethod(sumOfThree, 1, 2, 3)
\end{verbatim}

\textbf{ATTENTION}: They will be fewer errors and misunderstands if you'll set args types before each call of the function.

You can also pass arguments with different types:
\begin{verbatim}
threeTypes = libamico.getMethod("intStringLong", "(ILjava/lang/String;J)V")
libamico.callVoidMethod.argtypes = [ctypes.c_void_p, c_int, c_char_p, c_long]
libamico.callVoidMethod(threeTypes, 1, "int, String and long", 2)
\end{verbatim}

So, let's talk about passing arrays as arguments and receiving arrays as result of performing method. To pass array as argument you should to do three things before: set size of array(s) to pass, set arguments types for the function(it's a necessary step for arrays) and convert array to the tuple.

To set size of passed arrays use function \texttt{void setSizeOfArrays(unsigned int size, unsigned int* s)}. It takes 2 arguments: number of arrays to be passed and tuple, whose each element contains a size of each appropriate array by number.
\begin{verbatim}
ar1 = (1, 2, 3) # first array represented as tuple
ar2 = (4, 5, 6) # second array represented as tuple
# take ID of the method
arrays = libamico.getMethod("sumOfTwoIntArrays", "([I[I)V")
# set arguments types for setSizeOfArrays function
# first is an integer and second is an array
libamico.setSizeOfArrays.argtypes = [c_int, ListPOINTER(c_int)]
# call function to set size of arrays
libamico.setSizeOfArrays(2, (3, 3))
# set arguments types for the function to call a method
libamico.callVoidMethod.argtypes = [ctypes.c_void_p, 
                                    ListPOINTER(c_int),
                                    ListPOINTER(c_int)]
# call a method with an arrays as arguments
libamico.callVoidMethod(arrays, ar1, ar2)
\end{verbatim}

Here we are using a strange object named \texttt{ListPOINTER(object)} to tell \texttt{Python} that concrete argument is an array.  Here is a code of this object:
\begin{verbatim}
class ListPOINTER(object):
    def __init__(self, etype):
        self.etype = etype

    def from_param(self, param):
        if isinstance(param, (list, tuple)):
            return (self.etype * len(param))(*param)
        else:
            return param
\end{verbatim}
You need to insert this code in to your program to use it. Don't ask how does it works. It's a magic! ;)

To call a method that returns a tuple as result, use one of the functions from \texttt{PyObject* call<Type>ArrayMethod(void* midUInt, ...)} group depend on type of elements to be returned. Here you need to set u
p result type of the function to \texttt{py\_object}:
\begin{verbatim}
# take an ID of the method that will return an array of strings
array = libamico.getMethod("getStringArray", "()[Ljava/lang/String;")
# set types of arguments
libamico.callStringArrayMethod.argtypes = [ctypes.c_void_p]
# set result type
libamico.callStringArrayMethod.restype = py_object
# call method
strings = libamico.callStringArrayMethod(array)
# strings is a Python tuple with strings returned by getStringArray methodz
\end{verbatim}
\subsection{Specification of AmiCoPyJava Functions}
This section contains the complete specification of the AmiCoPyJava functions. For each function, we provide information on the following:
\begin{itemize}
\item function prototypes
\item a detailed description, including the parameters and return values
\end{itemize}
\newpage
{\LARGE \textbf{amicoInitialize}}
\begin{table}[hp]
\center{
\begin{tabular}{ p{3cm} p{12cm} }
	\textbf{Prototype}	&	void amicoInitialize(int nOptions, ...) \\\\
	\textbf{Description}	&	Creates a \texttt{JVM} with given startup options. 

						If they were errors they will be printed to the standard error output. \\\\
	\textbf{Parameters}	&	\texttt{nOptions}: number of startup options

						\texttt{Additional arguments}: variable list of JVM startup options given as strings(i.e. each parameter is a separate startup option).\\\\
	\textbf{Return Values}&	Doesn't return any value. \\\\
\end{tabular}
}
\end{table}
\newpage
{\LARGE \textbf{createGeneralEnvironment}}
\begin{table}[hp]
\center{
\begin{tabular}{ p{3cm} p{12cm} }
	\textbf{Prototype}	&	void createGeneralEnvironment(const char* javaClassName) \\\\
	\textbf{Description}	&	Loads a Java class in to the memory. 

						If they were errors they will be printed to the standard error output. \\\\
	\textbf{Parameters}	&	\texttt{javaClassName}: Path to the \texttt{Java} class to be loaded without suffix \texttt{.class}.\\\\
	\textbf{Return Values}&	Doesn't return any value. \\\\
\end{tabular}
}
\end{table}
\newpage
{\LARGE \textbf{destroyEnvironment}}
\begin{table}[hp]
\center{
\begin{tabular}{ p{3cm} p{12cm} }
	\textbf{Prototype}	&	void destroyEnvironment() \\\\
	\textbf{Description}	&	Unloads \texttt{Java} class from the memory and destroys JVM.

						If they were errors they will be printed to the standard error output. \\\\
	\textbf{Parameters}	&	Has no parameters.\\\\
	\textbf{Return Values}&	Doesn't return any value. \\\\
\end{tabular}
}
\end{table}
\newpage
{\LARGE \textbf{getMethod}}
\begin{table}[hp]
\center{
\begin{tabular}{ p{3cm} p{12cm} }
	\textbf{Prototype}	&	void* getMethod(const char* mName, const char* mSign)\\\\
	\textbf{Description}	&	Gets an ID of the method  and returns pointer to it. Pointer in \texttt{Python} is stored like a number.

						If they were errors they will be printed to the standard error output. \\\\
	\textbf{Parameters}	&	\texttt{mName}: Name of the method in the class.

						\texttt{mSign}: Signature of the method in the class. See \texttt{JNI} documentation for information about composing it.\\\\
	\textbf{Return Values}&	Returns a pointer to the method ID.  \\\\
\end{tabular}
}
\end{table}
\newpage
{\LARGE \textbf{call$<$Type$>$Method}}
\begin{table}[hp]
\center{
\begin{tabular}{ p{3cm} p{12cm} }
	\textbf{Prototype}	&	\texttt{$<$NativeType$>$ call$<$Type$>$Method(void* midUInt, ...)}\\\\
	\textbf{Forms}		&	This family of function consists of ten members.

						\begin{minipage}{0.4\textwidth}
						\center{
							\begin{tabular}{ | l | l |}
								\hline
								\textbf{call$<$Type$>$Method}	&	\textbf{$<$NativeType$>$} \\ \hline
								callVoidMethod				&	void \\ \hline
								callIntMethod				&	int \\ \hline
								callShortMethod				&	short \\ \hline
								callLongMethod				&	long \\ \hline
								callCharMethod				&	unsigned short \\ \hline
								callByteMethod				&	signed char \\ \hline
								callBooleanMethod			&	unsigned char \\ \hline
								callStringMethod				&	String \\ \hline
								callFloatMethod				&	float \\ \hline
								callDoubleMethod			&	float \\
								\hline 
							\end{tabular}
						}
						\end{minipage}\\\\
	\textbf{Description}	&	Invokes an instance method, specified using a method ID. Programmers place all arguments that are to be passed to the method immediately following the \texttt{midUInt} argument. The \texttt{call$<$Type$>$Method} function accepts these arguments, converts and passes them to the method that the programmer wishes to invoke.

						If they were errors they will be printed to the standard error output. \\\\
	\textbf{Parameters}	&	\texttt{midUInt}: An ID of the method, returned by \texttt{getMethod} function. 

						\texttt{Additional arguments}: Arguments to be passed in to the invokable method of the \texttt{Java} class.\\\\
	\textbf{Return Values}&	The result of calling the method.  \\\\
\end{tabular}
}
\end{table}
\newpage
{\LARGE \textbf{setSizeOfArrays}}
\begin{table}[hp]
\center{
\begin{tabular}{ p{3cm} p{12cm} }
	\textbf{Prototype}	&	void setSizeOfArrays(unsigned int size, unsigned int* ars)\\\\
	\textbf{Description}	&	Sets size of passed to the AmiCo function array(s).

						If they were errors they will be printed to the standard error output. \\\\
	\textbf{Parameters}	&	\texttt{size}: Number of elements in array, that will be passed to this method.  In other words \texttt{size} should be equal to the number of arrays that will be passed to the following function.

						\texttt{ars}: Array of length \texttt{size} of integers where each element means size of appropriate array in the following function.\\\\
	\textbf{Return Values}&	Doesn't return any value.  \\\\
\end{tabular}
}
\end{table}
\newpage
{\LARGE \textbf{call$<$Type$>$ArrayMethod}}
\begin{table}[hp]
\center{
\begin{tabular}{ p{3cm} p{12cm} }
	\textbf{Prototype}	&	\texttt{$<$NativeType$>$ call$<$Type$>$ArrayMethod(void* midUInt, ...)}\\\\
	\textbf{Forms}		&	This family of function consists of ten members.

						\begin{minipage}{0.4\textwidth}
						\center{
							\begin{tabular}{ | l | l |}
								\hline
								\textbf{call$<$Type$>$Method}	&	\textbf{$<$NativeType$>$} \\ \hline
								callIntArrayMethod				&	tuple of int \\ \hline
								callShortArrayMethod				&	tuple of short \\ \hline
								callLongArrayMethod				&	tuple of long \\ \hline
								callCharArrayMethod				&	tuple of unsigned short \\ \hline
								callByteArrayMethod				&	tuple of signed char \\ \hline
								callBooleanArrayMethod			&	tuple of unsigned char \\ \hline
								callStringArrayMethod				&	tuple of String \\ \hline
								callFloatArrayMethod				&	tuple of float \\ \hline
								callDoubleArrayMethod			&	tuple of float \\
								\hline 
							\end{tabular}
						}
						\end{minipage}\\\\
	\textbf{Description}	&	Invokes an instance method, specified using a method ID. Programmers place all arguments that are to be passed to the method immediately following the \texttt{midUInt} argument. The \texttt{call$<$Type$>$ArrayMethod} function accepts these arguments, converts and passes them to the method that the programmer wishes to invoke.

						If they were errors they will be printed to the standard error output. \\\\
	\textbf{Parameters}	&	\texttt{midUInt}: An ID of the method, returned by \texttt{getMethod} function. 

						\texttt{Additional arguments}: Arguments to be passed in to the invokable method of the \texttt{Java} class.\\\\
	\textbf{Return Values}&	The result of calling the method --- \texttt{Python} tuple.   \\\\
\end{tabular}
}
\end{table}
\newpage

\subsection{Compiling library}
To compile a library you need to have \texttt{Java} and \texttt{Python} include files installed as like as standard Developer Tools(explanations are in platform specific subsections). There are two ways to compile a library: using makefile or manual compiling. To compile using makefile just \texttt{cd} to the directory where you has downloaded sources and run \texttt{make}:
\begin{verbatim}
$ cd AmiCo/AmiCoPyJava
$ make
\end{verbatim}
After this step you'll have a new directory named \texttt{build}. Inside of this directory will be one file of the dynamic library --- \texttt{libAmiCoPyJava.dylib} if you are using \texttt{MacOS} or \texttt{libAmiCoPyJava.so} if you are using \texttt{Linux}. That's all! Library is ready for using! This way is equal for both MacOS and Linux and it will work perfect only if you have a standard system paths.
\subsubsection{Linux}
If you've decided to compile library manually than you should determine where is your \texttt{Java} and \texttt{Python} include files are located. Assume \texttt{Java} include files are located in \texttt{/usr/lib/jvm/java-6-sun/include} and \texttt{/usr/lib/jvm/java-6-sun/include/linux} directories and \texttt{Python} include files are located in \texttt{/usr/include/python2.6}. There are also several standard libraries that we will need to compile: \texttt{pthread, z, util}. We will need paths to JVM libraries too: \texttt{/usr/lib/jvm/java-6-sun/jre/lib} and \texttt{/usr/lib/jvm/java-6-sun/jre/lib/i386/server} (possibly, this paths will be different for you if you have non-standard system installation paths).

Well, now we have all that we need so we can start to compile(note, that commands should be in one line):
\begin{verbatim}
$ cd AmiCo/AmiCoPyJava
$ mkdir build
$ g++ -shared -Wl,-soname,libAmiCoPyJava.so.1 -fPIC -I/usr/include/python2.6 \
   -I/usr/lib/jvm/java-6-sun/include -I/usr/lib/jvm/java-6-sun/include/linux \
   -L/usr/lib/jvm/java-6-sun/jre/lib -L/usr/lib/jvm/java-6-sun/jre/lib/i386/server \
   -ljvm -lpthread -lz -lutil -o build/libAmiCoPyJava.so src/PythonCallsJava.cc
\end{verbatim}
After that you'll have a libAmiCoPyJava.so in \texttt{build} directory. That's all! Now you can use it!

\subsubsection{Mac}
Mac specific options

\subsection{Running a simple program(Hello Universe!)}
Now let's write our first example program that will demonstrate capabilities of the library. We'll call it HelloUniverce.

First of all we need a Java class whose methods will be called from the Python. This class will have following methods:
\begin{enumerate}
\item \texttt{void printHelloUniverce()} --- prints a simple string
\begin{verbatim}
public void printHelloUniverce()
{
    System.out.println("Hello Univerce!!!");
}
\end{verbatim}
\item \texttt{void printCustomString(String str)} --- prints a string passed from the Python as parameter
\begin{verbatim}
public void printCustomString(String str)
{
    System.out.println(str);
}
\end{verbatim}
\item \texttt{void passArrayOfIntegers(int[] array)} --- prints each element of the passed from the Python array
\begin{verbatim}
public void passArrayOfIntegers(int[] array)
{
    for (int i = 0; i < array.length; i++)
        System.out.println ("array[" + i + "] = " + array[i]);
}
\end{verbatim}
\item \texttt{float[] getArrayOfFloats()} --- returns an array of floats back to the Python
\begin{verbatim}
public float[] getArrayOfFloats()
{
    float[] res = {2.43f, 835.34536f, 2456.234f, -234.213f};
    return res;
}
\end{verbatim}
\item \texttt{String getIntAsString(int i)} --- takes integer as parameter, converts it to the string and returns string back to the Python
\begin{verbatim}
public String getIntAsString(int i)
{
    String s = String.valueOf(i);
    return s;
}
\end{verbatim}
\item \texttt{float sumOfFloatAndInt\_AsFloat(float fl, int i)} --- takes float and integer arguments, adds them and returns sum as float
\begin{verbatim}
public float sumOfFloatAndInt_AsFloat(float fl, int i)
{
    System.out.println("float: " + fl);
    System.out.println("integer: " + i);
    return (float) (fl+i);
}
\end{verbatim}
\item \texttt{void passLong(long l)} --- Takes a long number as argument and prints information about size of types in C++, Python and Java
\begin{verbatim}
public void passLong(long l)
{
    System.out.println("Maximal value of Java long is:     " + Long.MAX_VALUE);
    System.out.println("Maximal value of C++ long long is: 9223372036854775807");
    System.out.println("Value passed from Python as long:  " + l);
}
\end{verbatim}
\end{enumerate}
Assume that you have saved your class in the directory named \texttt{example}. Let's go to this directory and compile a class:
\begin{verbatim}
$ cd example
$ javac HelloUniverce.java
\end{verbatim}
When compilation finished you'll see a \texttt{HelloUniverce.class} file. That's what we need. The next step is more difficult than previous: we will compile library \texttt{AmiCoPyJava} to get a loadable file of the dynamic library. We has already described this step in section \textbf{Compiling library}.

After you've compiled a library and get a \texttt{libAmiCoPyJava.so} file for \texttt{Linux} or \texttt{libAmiCoPyJava.dylib} file for \texttt{MacOS} it's time to write a Python program that will use this library to call methods from the \texttt{Java} class. First of all we need to import some modules:
\begin{verbatim}
import sys
import ctypes
from ctypes import *
from ctypes.util import find_library
\end{verbatim}
If we will pass arrays between Python and Java, that we should implement one very important class, that will make passing arrays as arguments possible:
\begin{verbatim}
class ListPOINTER(object):
    def __init__(self, etype):
        self.etype = etype

    def from_param(self, param):
        if isinstance(param, (list, tuple)):
            return (self.etype * len(param))(*param)
        else:
            return param
\end{verbatim}
Now, we need to load a library in to a Python program. If you are a Linux user then use this variant:
\begin{verbatim}
loadName = './libAmiCoPyJava.so'
libamico = ctypes.CDLL(loadName)
\end{verbatim}
If you are a Mac user then use this variant:
\begin{verbatim}
name =  'AmiCoPyJava' # name of the library
loadName = find_library(name)
libamico = ctypes.CDLL(loadName)
\end{verbatim}
Note, that \texttt{libamico} should be a global variable to be accessed from any function. So, we have loaded a library and now we need to create a \texttt{JVM} and load a class:
\begin{verbatim}
#create JVM without any additional startup options
libamico.amicoInitialize(0)
#set internal amico types (local function)
initAmiCo()
#load a class in to the JVM
className = "HelloUniverce"    
libamico.createGeneralEnvironment(className)
\end{verbatim}
Now we are ready to call any method from the class using a AmiCo functions. Let's write a separate function for each method:
\begin{verbatim}
def FuncPrintHelloUniverce():
    """Calls method that prints a simple string 'Hello Univerce!!!'"""
    #use global variable
    global libamico
    #take a method ID
    helloUniverce = libamico.getMethod("printHelloUniverce", "()V")
    #method doesn't return any value so we use a 'callVoidMethod' function
    libamico.callVoidMethod(helloUniverce)
    
def FuncPrintCustomString(str):
    """Passes a string in to the Java method"""
    global libamico
    #take a method ID
    printCustomString = libamico.getMethod("printCustomString", "(Ljava/lang/String;)V")
    #function callVoidMethod takes a C pointer and a string as parameters
    libamico.callVoidMethod.argtypes = [ctypes.c_void_p,  c_char_p]
    #method doesn't return any value so we use a 'callVoidMethod' function
    libamico.callVoidMethod(printCustomString, str)
    
def FuncPassArrayOfIntegers():
    """Calls the method that takes an array of integers as parameter and 
    prints this array to the screen"""
    array = [1, 2, 3]
    #take a method ID
    passArrayOfIntegers = libamico.getMethod("passArrayOfIntegers", "([I)V")
    #function callVoidMethod takes a C pointer and a Python tuple
    libamico.callVoidMethod.argtypes = [c_void_p,  ListPOINTER(c_int)]
    #cause there is an array in parameters we need to set it's size
    #we pass 1 array with length 3
    libamico.setSizeOfArrays(1, (3,))
    #method doesn't return any value so we use a 'callVoidMethod' function
    libamico.callVoidMethod(passArrayOfIntegers, tuple(array))
    
def FuncGetArrayOfFloats():
    """Calls a method that will return an array of floats"""
    #take a method ID
    getArrayOfFloats = libamico.getMethod("getArrayOfFloats", "()[F")
    #function callFloatArrayMethod takes only one
    #required argument -- ID of the method to be called
    libamico.callFloatArrayMethod.argtypes = [c_void_p]
    #function 'callFloatArrayMethod' will return result of
    #caling 'getArrayOfFloats' method,
    #i.e. an array of floats
    res = libamico.callFloatArrayMethod(getArrayOfFloats)
    print "result of 'getArrayOfFloats' method: ", res
    
def FuncGetIntAsString():
    """Calls method with parameter -- integer and takes a result of calling
    this method -- a string representation of the passed integer"""
    #take a method ID
    getIntAsString = libamico.getMethod("getIntAsString", "(I)Ljava/lang/String;")
    #takes a method ID and an integer number.
    #Type of returning value was changed in 'initAmiCo' function
    libamico.callStringMethod.argtypes = [c_void_p, c_int]
    #method returns a Sting value so we use 'callStringMethod' function
    res = libamico.callStringMethod(getIntAsString, 5)
    print "result of 'getIntAsString' method: ", res

def FuncSumOfFloatAndInt_AsFloat():
     """Calls a method that takes two parameters -- float pointing number and an
    integer number and returns a float pointing number -- sum of this two numbers"""
    sumOfFloatAndInt_AsFloat = libamico.getMethod("sumOfFloatAndInt_AsFloat", "(FI)F")
    #takes C pointer, double and int.
    #Yes, exactly double. When do you pass a float pointing number in to a method it
    #should have a type double casue of some C++ restrictions, but in Java method
    #should take a float
    libamico.callFloatMethod.argtypes = [c_void_p, c_double, c_int]
    #returns a float
    res = libamico.callFloatMethod(sumOfFloatAndInt_AsFloat, c_double(2.2), c_int(5))
    print "result of 'sumOfFloatAndInt_AsFloat' method: ", res
    
def passLong():
    """Passes in to a Java method maximal value of type long in Java and Python"""
    passLong = libamico.getMethod("passLong", "(J)V")
    #Java's and Python's long type is equivalent to long long or __int64 in C++
    libamico.callVoidMethod.argtypes = [c_void_p, c_longlong]
    libamico.callVoidMethod(passLong, 9223372036854775807)
\end{verbatim}
 And in the end we should destroy a JVM using \texttt{destroyEnvironment} function from \texttt{libamico}. Note, that file of the dynamic library, compiled \texttt{Java} class and a \texttt{Python} program should be located in the same directory.

If you got an error message when do you run a python program like this:
\begin{verbatim}
OSError: libjvm.so: cannot open shared object file: No such file or directory
\end{verbatim}
that means that you don't have correct path to your \texttt{Java} dynamic libraries. In that case try to run your program using an \texttt{AmiCoRunner.sh} script located in the root directory of the \texttt{AmiCoPyJava} project. If you still have any error messages then contact with developers to solve your problem.
\end{document}
